Skip to main content

MockMvc Spring Boot Testing Guide

Table of Contents​

  1. Introduction to MockMvc
  2. Setting Up Test Dependencies
  3. Testing Controllers
  4. Testing Services
  5. Testing Repositories
  6. Integration Testing
  7. Testing Security
  8. Testing JSON Serialization/Deserialization
  9. Testing Exception Handling
  10. Advanced Testing Techniques
  11. Best Practices

Introduction to MockMvc​

MockMvc is a powerful testing framework in Spring Boot that allows you to test Spring MVC controllers without starting a full HTTP server. It provides a fluent API for performing HTTP requests and validating responses.

Key Benefits​

  • Fast execution - No need to start a web server
  • Isolated testing - Test specific layers independently
  • Comprehensive assertions - Rich API for validating responses
  • Mock integration - Easy integration with Mockito

Setting Up Test Dependencies​

Maven Dependencies​

<dependencies>
    <!-- Spring Boot Test Starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>

    <!-- Spring Boot Web Starter (for MockMvc) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring Security Test (if using security) -->
    <dependency>
        <groupId>org.springframework.security</groupId>
        <artifactId>spring-security-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

Gradle Dependencies​

dependencies {
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.security:spring-security-test' // if using security
}

Testing Controllers​

Basic Controller Test Setup​

@WebMvcTest(UserController.class)
class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private UserService userService;

    @Test
    void shouldGetUserById() throws Exception {
        // Given
        User user = new User(1L, "John Doe", "john@example.com");
        when(userService.findById(1L)).thenReturn(user);

        // When & Then
        mockMvc.perform(get("/api/users/1"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.id").value(1))
                .andExpect(jsonPath("$.name").value("John Doe"))
                .andExpect(jsonPath("$.email").value("john@example.com"));
    }
}

Testing POST Requests​

@Test
void shouldCreateUser() throws Exception {
    // Given
    User newUser = new User(null, "Jane Doe", "jane@example.com");
    User savedUser = new User(2L, "Jane Doe", "jane@example.com");

    when(userService.save(any(User.class))).thenReturn(savedUser);

    // When & Then
    mockMvc.perform(post("/api/users")
            .contentType(MediaType.APPLICATION_JSON)
            .content("""
                {
                    "name": "Jane Doe",
                    "email": "jane@example.com"
                }
                """))
            .andExpect(status().isCreated())
            .andExpect(jsonPath("$.id").value(2))
            .andExpect(jsonPath("$.name").value("Jane Doe"));
}

Testing PUT Requests​

@Test
void shouldUpdateUser() throws Exception {
    // Given
    User updatedUser = new User(1L, "John Smith", "johnsmith@example.com");
    when(userService.update(eq(1L), any(User.class))).thenReturn(updatedUser);

    // When & Then
    mockMvc.perform(put("/api/users/1")
            .contentType(MediaType.APPLICATION_JSON)
            .content("""
                {
                    "name": "John Smith",
                    "email": "johnsmith@example.com"
                }
                """))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.name").value("John Smith"));
}

Testing DELETE Requests​

@Test
void shouldDeleteUser() throws Exception {
    // Given
    doNothing().when(userService).deleteById(1L);

    // When & Then
    mockMvc.perform(delete("/api/users/1"))
            .andExpect(status().isNoContent());

    verify(userService).deleteById(1L);
}

Testing Query Parameters​

@Test
void shouldGetUsersWithPagination() throws Exception {
    // Given
    List<User> users = Arrays.asList(
        new User(1L, "John", "john@example.com"),
        new User(2L, "Jane", "jane@example.com")
    );

    when(userService.findAll(0, 10)).thenReturn(users);

    // When & Then
    mockMvc.perform(get("/api/users")
            .param("page", "0")
            .param("size", "10"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$", hasSize(2)))
            .andExpect(jsonPath("$[0].name").value("John"))
            .andExpect(jsonPath("$[1].name").value("Jane"));
}

Testing Request Headers​

@Test
void shouldAcceptCustomHeader() throws Exception {
    mockMvc.perform(get("/api/users/1")
            .header("X-Request-ID", "12345")
            .header("Accept", MediaType.APPLICATION_JSON_VALUE))
            .andExpect(status().isOk());
}

Testing Services​

Unit Testing Services with Mockito​

@ExtendWith(MockitoExtension.class)
class UserServiceTest {

    @Mock
    private UserRepository userRepository;

    @Mock
    private EmailService emailService;

    @InjectMocks
    private UserService userService;

    @Test
    void shouldFindUserById() {
        // Given
        User user = new User(1L, "John Doe", "john@example.com");
        when(userRepository.findById(1L)).thenReturn(Optional.of(user));

        // When
        User result = userService.findById(1L);

        // Then
        assertThat(result).isNotNull();
        assertThat(result.getName()).isEqualTo("John Doe");
        verify(userRepository).findById(1L);
    }

    @Test
    void shouldThrowExceptionWhenUserNotFound() {
        // Given
        when(userRepository.findById(1L)).thenReturn(Optional.empty());

        // When & Then
        assertThatThrownBy(() -> userService.findById(1L))
                .isInstanceOf(UserNotFoundException.class)
                .hasMessage("User not found with id: 1");
    }

    @Test
    void shouldSaveUserAndSendWelcomeEmail() {
        // Given
        User user = new User(null, "John Doe", "john@example.com");
        User savedUser = new User(1L, "John Doe", "john@example.com");

        when(userRepository.save(user)).thenReturn(savedUser);

        // When
        User result = userService.save(user);

        // Then
        assertThat(result.getId()).isEqualTo(1L);
        verify(userRepository).save(user);
        verify(emailService).sendWelcomeEmail("john@example.com");
    }
}

Testing Service with @MockBean in Spring Context​

@SpringBootTest
class UserServiceIntegrationTest {

    @MockBean
    private UserRepository userRepository;

    @Autowired
    private UserService userService;

    @Test
    void shouldFindAllUsers() {
        // Given
        List<User> users = Arrays.asList(
            new User(1L, "John", "john@example.com"),
            new User(2L, "Jane", "jane@example.com")
        );
        when(userRepository.findAll()).thenReturn(users);

        // When
        List<User> result = userService.findAll();

        // Then
        assertThat(result).hasSize(2);
        assertThat(result.get(0).getName()).isEqualTo("John");
    }
}

Testing Repositories​

Testing JPA Repositories with @DataJpaTest​

@DataJpaTest
class UserRepositoryTest {

    @Autowired
    private TestEntityManager entityManager;

    @Autowired
    private UserRepository userRepository;

    @Test
    void shouldFindUserByEmail() {
        // Given
        User user = new User(null, "John Doe", "john@example.com");
        entityManager.persistAndFlush(user);

        // When
        Optional<User> result = userRepository.findByEmail("john@example.com");

        // Then
        assertThat(result).isPresent();
        assertThat(result.get().getName()).isEqualTo("John Doe");
    }

    @Test
    void shouldFindUsersByNameContaining() {
        // Given
        User user1 = new User(null, "John Doe", "john@example.com");
        User user2 = new User(null, "Jane Doe", "jane@example.com");
        User user3 = new User(null, "Bob Smith", "bob@example.com");

        entityManager.persistAndFlush(user1);
        entityManager.persistAndFlush(user2);
        entityManager.persistAndFlush(user3);

        // When
        List<User> result = userRepository.findByNameContaining("Doe");

        // Then
        assertThat(result).hasSize(2);
        assertThat(result).extracting(User::getName)
                .containsExactlyInAnyOrder("John Doe", "Jane Doe");
    }

    @Test
    void shouldDeleteUserById() {
        // Given
        User user = new User(null, "John Doe", "john@example.com");
        User savedUser = entityManager.persistAndFlush(user);

        // When
        userRepository.deleteById(savedUser.getId());

        // Then
        Optional<User> result = userRepository.findById(savedUser.getId());
        assertThat(result).isEmpty();
    }
}

Testing Custom Repository Methods​

@DataJpaTest
class UserRepositoryCustomTest {

    @Autowired
    private UserRepository userRepository;

    @Test
    @Sql("/test-data.sql") // Load test data from SQL file
    void shouldFindActiveUsersCreatedAfterDate() {
        // Given
        LocalDateTime cutoffDate = LocalDateTime.of(2023, 1, 1, 0, 0);

        // When
        List<User> result = userRepository.findActiveUsersCreatedAfter(cutoffDate);

        // Then
        assertThat(result).isNotEmpty();
        assertThat(result).allMatch(user ->
            user.isActive() && user.getCreatedAt().isAfter(cutoffDate));
    }
}

Integration Testing​

Full Integration Test with @SpringBootTest​

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@Testcontainers
class UserIntegrationTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:13")
            .withDatabaseName("testdb")
            .withUsername("test")
            .withPassword("test");

    @Autowired
    private TestRestTemplate restTemplate;

    @Autowired
    private UserRepository userRepository;

    @Test
    void shouldCreateAndRetrieveUser() {
        // Given
        User user = new User(null, "Integration Test User", "integration@example.com");

        // When - Create user
        ResponseEntity<User> createResponse = restTemplate.postForEntity(
                "/api/users", user, User.class);

        // Then - Verify creation
        assertThat(createResponse.getStatusCode()).isEqualTo(HttpStatus.CREATED);
        assertThat(createResponse.getBody()).isNotNull();
        Long userId = createResponse.getBody().getId();

        // When - Retrieve user
        ResponseEntity<User> getResponse = restTemplate.getForEntity(
                "/api/users/" + userId, User.class);

        // Then - Verify retrieval
        assertThat(getResponse.getStatusCode()).isEqualTo(HttpStatus.OK);
        assertThat(getResponse.getBody().getName()).isEqualTo("Integration Test User");

        // Verify in database
        Optional<User> dbUser = userRepository.findById(userId);
        assertThat(dbUser).isPresent();
    }
}

Testing with MockMvc and Real Database​

@SpringBootTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@AutoConfigureMockMvc
@Transactional
class UserControllerIntegrationTest {

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private UserRepository userRepository;

    @Test
    void shouldCreateUserInDatabase() throws Exception {
        // When
        mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content("""
                    {
                        "name": "Database Test User",
                        "email": "dbtest@example.com"
                    }
                    """))
                .andExpect(status().isCreated())
                .andExpect(jsonPath("$.id").exists());

        // Then - Verify in database
        Optional<User> user = userRepository.findByEmail("dbtest@example.com");
        assertThat(user).isPresent();
        assertThat(user.get().getName()).isEqualTo("Database Test User");
    }
}

Testing Security​

Testing Secured Endpoints​

@WebMvcTest(UserController.class)
@Import(SecurityConfig.class)
class UserControllerSecurityTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private UserService userService;

    @Test
    void shouldReturnUnauthorizedWhenNoToken() throws Exception {
        mockMvc.perform(get("/api/users/1"))
                .andExpect(status().isUnauthorized());
    }

    @Test
    @WithMockUser(roles = "USER")
    void shouldAllowUserRoleAccess() throws Exception {
        User user = new User(1L, "John", "john@example.com");
        when(userService.findById(1L)).thenReturn(user);

        mockMvc.perform(get("/api/users/1"))
                .andExpect(status().isOk());
    }

    @Test
    @WithMockUser(roles = "ADMIN")
    void shouldAllowAdminToDeleteUser() throws Exception {
        doNothing().when(userService).deleteById(1L);

        mockMvc.perform(delete("/api/users/1"))
                .andExpect(status().isNoContent());
    }

    @Test
    @WithMockUser(roles = "USER")
    void shouldForbidUserFromDeletingUser() throws Exception {
        mockMvc.perform(delete("/api/users/1"))
                .andExpect(status().isForbidden());
    }
}

Testing JWT Authentication​

@Test
void shouldAuthenticateWithValidJWT() throws Exception {
    String token = jwtTokenProvider.createToken("john@example.com", Arrays.asList("ROLE_USER"));

    mockMvc.perform(get("/api/users/profile")
            .header("Authorization", "Bearer " + token))
            .andExpect(status().isOk());
}

Testing JSON Serialization/Deserialization​

Testing JSON Serialization with @JsonTest​

@JsonTest
class UserJsonTest {

    @Autowired
    private JacksonTester<User> json;

    @Test
    void shouldSerializeUser() throws Exception {
        User user = new User(1L, "John Doe", "john@example.com");

        assertThat(json.write(user)).isEqualToJson("expected-user.json");
        assertThat(json.write(user)).hasJsonPathStringValue("@.name");
        assertThat(json.write(user)).extractingJsonPathStringValue("@.name")
                .isEqualTo("John Doe");
    }

    @Test
    void shouldDeserializeUser() throws Exception {
        String jsonContent = """
            {
                "id": 1,
                "name": "John Doe",
                "email": "john@example.com"
            }
            """;

        assertThat(json.parse(jsonContent))
                .usingRecursiveComparison()
                .isEqualTo(new User(1L, "John Doe", "john@example.com"));
    }
}

Testing Exception Handling​

Testing Global Exception Handler​

@WebMvcTest(UserController.class)
class UserControllerExceptionTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private UserService userService;

    @Test
    void shouldHandleUserNotFoundException() throws Exception {
        when(userService.findById(999L))
                .thenThrow(new UserNotFoundException("User not found with id: 999"));

        mockMvc.perform(get("/api/users/999"))
                .andExpect(status().isNotFound())
                .andExpect(jsonPath("$.message").value("User not found with id: 999"))
                .andExpect(jsonPath("$.timestamp").exists());
    }

    @Test
    void shouldHandleValidationErrors() throws Exception {
        mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content("""
                    {
                        "name": "",
                        "email": "invalid-email"
                    }
                    """))
                .andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.validationErrors").exists())
                .andExpect(jsonPath("$.validationErrors.name").value("Name is required"))
                .andExpect(jsonPath("$.validationErrors.email").value("Email format is invalid"));
    }
}

Advanced Testing Techniques​

Testing File Uploads​

@Test
void shouldUploadUserProfilePicture() throws Exception {
    MockMultipartFile file = new MockMultipartFile(
            "file",
            "profile.jpg",
            MediaType.IMAGE_JPEG_VALUE,
            "image content".getBytes());

    mockMvc.perform(multipart("/api/users/1/profile-picture")
            .file(file))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.message").value("Profile picture uploaded successfully"));
}

Testing Async Operations​

@Test
void shouldProcessAsyncUserRegistration() throws Exception {
    when(userService.registerAsync(any(User.class)))
            .thenReturn(CompletableFuture.completedFuture("Registration completed"));

    MvcResult result = mockMvc.perform(post("/api/users/register-async")
            .contentType(MediaType.APPLICATION_JSON)
            .content("""
                {
                    "name": "Async User",
                    "email": "async@example.com"
                }
                """))
            .andExpect(request().asyncStarted())
            .andReturn();

    mockMvc.perform(asyncDispatch(result))
            .andExpect(status().isOk())
            .andExpect(content().string("Registration completed"));
}

Testing with Custom Argument Resolvers​

@WebMvcTest(UserController.class)
@Import(CustomArgumentResolverConfig.class)
class UserControllerCustomResolverTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void shouldResolveCurrentUserFromToken() throws Exception {
        mockMvc.perform(get("/api/users/current")
                .header("Authorization", "Bearer valid-jwt-token"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.name").value("Current User"));
    }
}

Testing Caching​

@SpringBootTest
@AutoConfigureMockMvc
class UserCachingTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private UserRepository userRepository;

    @Test
    void shouldCacheUserData() throws Exception {
        User user = new User(1L, "John", "john@example.com");
        when(userRepository.findById(1L)).thenReturn(Optional.of(user));

        // First call - should hit the repository
        mockMvc.perform(get("/api/users/1"))
                .andExpect(status().isOk());

        // Second call - should use cache
        mockMvc.perform(get("/api/users/1"))
                .andExpect(status().isOk());

        // Verify repository was called only once
        verify(userRepository, times(1)).findById(1L);
    }
}

Best Practices​

1. Test Organization​

@DisplayName("User Controller Tests")
class UserControllerTest {

    @Nested
    @DisplayName("GET /api/users/{id}")
    class GetUserById {

        @Test
        @DisplayName("Should return user when valid ID provided")
        void shouldReturnUser_WhenValidIdProvided() {
            // Test implementation
        }

        @Test
        @DisplayName("Should return 404 when user not found")
        void shouldReturn404_WhenUserNotFound() {
            // Test implementation
        }
    }

    @Nested
    @DisplayName("POST /api/users")
    class CreateUser {

        @Test
        @DisplayName("Should create user with valid data")
        void shouldCreateUser_WithValidData() {
            // Test implementation
        }
    }
}

2. Test Data Builders​

public class UserTestDataBuilder {
    private Long id = 1L;
    private String name = "John Doe";
    private String email = "john@example.com";
    private boolean active = true;

    public static UserTestDataBuilder aUser() {
        return new UserTestDataBuilder();
    }

    public UserTestDataBuilder withId(Long id) {
        this.id = id;
        return this;
    }

    public UserTestDataBuilder withName(String name) {
        this.name = name;
        return this;
    }

    public UserTestDataBuilder withEmail(String email) {
        this.email = email;
        return this;
    }

    public UserTestDataBuilder inactive() {
        this.active = false;
        return this;
    }

    public User build() {
        return new User(id, name, email, active);
    }
}

// Usage in tests
@Test
void shouldCreateInactiveUser() {
    User user = aUser().withName("Jane").inactive().build();
    // Test with user
}

3. Custom Matchers​

public class UserMatchers {

    public static Matcher<User> hasName(String expectedName) {
        return new TypeSafeMatcher<User>() {
            @Override
            protected boolean matchesSafely(User user) {
                return Objects.equals(user.getName(), expectedName);
            }

            @Override
            public void describeTo(Description description) {
                description.appendText("user with name ").appendValue(expectedName);
            }
        };
    }
}

// Usage
assertThat(user, hasName("John Doe"));

4. Test Configuration​

@TestConfiguration
public class TestConfig {

    @Bean
    @Primary
    public Clock testClock() {
        return Clock.fixed(Instant.parse("2023-01-01T00:00:00Z"), ZoneOffset.UTC);
    }

    @Bean
    @Primary
    public EmailService mockEmailService() {
        return Mockito.mock(EmailService.class);
    }
}

5. Test Profiles​

# application-test.yml
spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
  jpa:
    hibernate:
      ddl-auto: create-drop
  logging:
    level:
      org.springframework.web: DEBUG

6. Parameterized Tests​

@ParameterizedTest
@ValueSource(strings = {"", " ", "invalid-email", "@example.com"})
void shouldRejectInvalidEmails(String invalidEmail) throws Exception {
    mockMvc.perform(post("/api/users")
            .contentType(MediaType.APPLICATION_JSON)
            .content(String.format("""
                {
                    "name": "Test User",
                    "email": "%s"
                }
                """, invalidEmail)))
            .andExpect(status().isBadRequest());
}

@ParameterizedTest
@CsvSource({
    "1, John, john@example.com",
    "2, Jane, jane@example.com",
    "3, Bob, bob@example.com"
})
void shouldReturnUsersWithValidData(Long id, String name, String email) throws Exception {
    User user = new User(id, name, email);
    when(userService.findById(id)).thenReturn(user);

    mockMvc.perform(get("/api/users/" + id))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.name").value(name))
            .andExpect(jsonPath("$.email").value(email));
}

Summary​

This guide covers comprehensive testing strategies for Spring Boot applications using MockMvc:

  • Controller Testing: Unit tests with mocked dependencies
  • Service Testing: Business logic validation with mocked repositories
  • Repository Testing: Data access layer testing with @DataJpaTest
  • Integration Testing: End-to-end testing with real databases
  • Security Testing: Authentication and authorization testing
  • Advanced Techniques: File uploads, async operations, caching

Remember to:

  • Use appropriate test slices (@WebMvcTest, @DataJpaTest, @JsonTest)
  • Mock external dependencies appropriately
  • Write clear, descriptive test names
  • Organize tests logically with @Nested classes
  • Use test data builders for complex objects
  • Follow the AAA pattern (Arrange, Act, Assert)
  • Keep tests independent and repeatable